home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / sgtsvx.z / sgtsvx
Encoding:
Text File  |  2002-10-03  |  10.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSGGGGTTTTSSSSVVVVXXXX((((3333SSSS))))                                                          SSSSGGGGTTTTSSSSVVVVXXXX((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SGTSVX - use the LU factorization to compute the solution to a real
  10.      system of linear equations A * X = B or A**T * X = B,
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE SGTSVX( FACT, TRANS, N, NRHS, DL, D, DU, DLF, DF, DUF, DU2,
  14.                         IPIV, B, LDB, X, LDX, RCOND, FERR, BERR, WORK, IWORK,
  15.                         INFO )
  16.  
  17.          CHARACTER      FACT, TRANS
  18.  
  19.          INTEGER        INFO, LDB, LDX, N, NRHS
  20.  
  21.          REAL           RCOND
  22.  
  23.          INTEGER        IPIV( * ), IWORK( * )
  24.  
  25.          REAL           B( LDB, * ), BERR( * ), D( * ), DF( * ), DL( * ), DLF(
  26.                         * ), DU( * ), DU2( * ), DUF( * ), FERR( * ), WORK( *
  27.                         ), X( LDX, * )
  28.  
  29. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  30.      These routines are part of the SCSL Scientific Library and can be loaded
  31.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  32.      directs the linker to use the multi-processor version of the library.
  33.  
  34.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  35.      4 bytes (32 bits). Another version of SCSL is available in which integers
  36.      are 8 bytes (64 bits).  This version allows the user access to larger
  37.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  38.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  39.      only one of the two versions; 4-byte integer and 8-byte integer library
  40.      calls cannot be mixed.
  41.  
  42. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  43.      SGTSVX uses the LU factorization to compute the solution to a real system
  44.      of linear equations A * X = B or A**T * X = B, where A is a tridiagonal
  45.      matrix of order N and X and B are N-by-NRHS matrices.
  46.  
  47.      Error bounds on the solution and a condition estimate are also provided.
  48.  
  49.  
  50. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  51.      The following steps are performed:
  52.  
  53.      1. If FACT = 'N', the LU decomposition is used to factor the matrix A
  54.         as A = L * U, where L is a product of permutation and unit lower
  55.         bidiagonal matrices and U is upper triangular with nonzeros in
  56.         only the main diagonal and first two superdiagonals.
  57.  
  58.      2. If some U(i,i)=0, so that U is exactly singular, then the routine
  59.         returns with INFO = i. Otherwise, the factored form of A is used
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSGGGGTTTTSSSSVVVVXXXX((((3333SSSS))))                                                          SSSSGGGGTTTTSSSSVVVVXXXX((((3333SSSS))))
  71.  
  72.  
  73.  
  74.         to estimate the condition number of the matrix A.  If the
  75.         reciprocal of the condition number is less than machine precision,
  76.         INFO = N+1 is returned as a warning, but the routine still goes on
  77.         to solve for X and compute error bounds as described below.
  78.  
  79.      3. The system of equations is solved for X using the factored form
  80.         of A.
  81.  
  82.      4. Iterative refinement is applied to improve the computed solution
  83.         matrix and calculate error bounds and backward error estimates
  84.         for it.
  85.  
  86.  
  87. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  88.      FACT    (input) CHARACTER*1
  89.              Specifies whether or not the factored form of A has been supplied
  90.              on entry.  = 'F':  DLF, DF, DUF, DU2, and IPIV contain the
  91.              factored form of A; DL, D, DU, DLF, DF, DUF, DU2 and IPIV will
  92.              not be modified.  = 'N':  The matrix will be copied to DLF, DF,
  93.              and DUF and factored.
  94.  
  95.      TRANS   (input) CHARACTER*1
  96.              Specifies the form of the system of equations:
  97.              = 'N':  A * X = B     (No transpose)
  98.              = 'T':  A**T * X = B  (Transpose)
  99.              = 'C':  A**H * X = B  (Conjugate transpose = Transpose)
  100.  
  101.      N       (input) INTEGER
  102.              The order of the matrix A.  N >= 0.
  103.  
  104.      NRHS    (input) INTEGER
  105.              The number of right hand sides, i.e., the number of columns of
  106.              the matrix B.  NRHS >= 0.
  107.  
  108.      DL      (input) REAL array, dimension (N-1)
  109.              The (n-1) subdiagonal elements of A.
  110.  
  111.      D       (input) REAL array, dimension (N)
  112.              The n diagonal elements of A.
  113.  
  114.      DU      (input) REAL array, dimension (N-1)
  115.              The (n-1) superdiagonal elements of A.
  116.  
  117.      DLF     (input or output) REAL array, dimension (N-1)
  118.              If FACT = 'F', then DLF is an input argument and on entry
  119.              contains the (n-1) multipliers that define the matrix L from the
  120.              LU factorization of A as computed by SGTTRF.
  121.  
  122.              If FACT = 'N', then DLF is an output argument and on exit
  123.              contains the (n-1) multipliers that define the matrix L from the
  124.              LU factorization of A.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSGGGGTTTTSSSSVVVVXXXX((((3333SSSS))))                                                          SSSSGGGGTTTTSSSSVVVVXXXX((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      DF      (input or output) REAL array, dimension (N)
  141.              If FACT = 'F', then DF is an input argument and on entry contains
  142.              the n diagonal elements of the upper triangular matrix U from the
  143.              LU factorization of A.
  144.  
  145.              If FACT = 'N', then DF is an output argument and on exit contains
  146.              the n diagonal elements of the upper triangular matrix U from the
  147.              LU factorization of A.
  148.  
  149.      DUF     (input or output) REAL array, dimension (N-1)
  150.              If FACT = 'F', then DUF is an input argument and on entry
  151.              contains the (n-1) elements of the first superdiagonal of U.
  152.  
  153.              If FACT = 'N', then DUF is an output argument and on exit
  154.              contains the (n-1) elements of the first superdiagonal of U.
  155.  
  156.      DU2     (input or output) REAL array, dimension (N-2)
  157.              If FACT = 'F', then DU2 is an input argument and on entry
  158.              contains the (n-2) elements of the second superdiagonal of U.
  159.  
  160.              If FACT = 'N', then DU2 is an output argument and on exit
  161.              contains the (n-2) elements of the second superdiagonal of U.
  162.  
  163.      IPIV    (input or output) INTEGER array, dimension (N)
  164.              If FACT = 'F', then IPIV is an input argument and on entry
  165.              contains the pivot indices from the LU factorization of A as
  166.              computed by SGTTRF.
  167.  
  168.              If FACT = 'N', then IPIV is an output argument and on exit
  169.              contains the pivot indices from the LU factorization of A; row i
  170.              of the matrix was interchanged with row IPIV(i).  IPIV(i) will
  171.              always be either i or i+1; IPIV(i) = i indicates a row
  172.              interchange was not required.
  173.  
  174.      B       (input) REAL array, dimension (LDB,NRHS)
  175.              The N-by-NRHS right hand side matrix B.
  176.  
  177.      LDB     (input) INTEGER
  178.              The leading dimension of the array B.  LDB >= max(1,N).
  179.  
  180.      X       (output) REAL array, dimension (LDX,NRHS)
  181.              If INFO = 0 or INFO = N+1, the N-by-NRHS solution matrix X.
  182.  
  183.      LDX     (input) INTEGER
  184.              The leading dimension of the array X.  LDX >= max(1,N).
  185.  
  186.      RCOND   (output) REAL
  187.              The estimate of the reciprocal condition number of the matrix A.
  188.              If RCOND is less than the machine precision (in particular, if
  189.              RCOND = 0), the matrix is singular to working precision.  This
  190.              condition is indicated by a return code of INFO > 0.
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSGGGGTTTTSSSSVVVVXXXX((((3333SSSS))))                                                          SSSSGGGGTTTTSSSSVVVVXXXX((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      FERR    (output) REAL array, dimension (NRHS)
  207.              The estimated forward error bound for each solution vector X(j)
  208.              (the j-th column of the solution matrix X).  If XTRUE is the true
  209.              solution corresponding to X(j), FERR(j) is an estimated upper
  210.              bound for the magnitude of the largest element in (X(j) - XTRUE)
  211.              divided by the magnitude of the largest element in X(j).  The
  212.              estimate is as reliable as the estimate for RCOND, and is almost
  213.              always a slight overestimate of the true error.
  214.  
  215.      BERR    (output) REAL array, dimension (NRHS)
  216.              The componentwise relative backward error of each solution vector
  217.              X(j) (i.e., the smallest relative change in any element of A or B
  218.              that makes X(j) an exact solution).
  219.  
  220.      WORK    (workspace) REAL array, dimension (3*N)
  221.  
  222.      IWORK   (workspace) INTEGER array, dimension (N)
  223.  
  224.      INFO    (output) INTEGER
  225.              = 0:  successful exit
  226.              < 0:  if INFO = -i, the i-th argument had an illegal value
  227.              > 0:  if INFO = i, and i is
  228.              <= N:  U(i,i) is exactly zero.  The factorization has not been
  229.              completed unless i = N, but the factor U is exactly singular, so
  230.              the solution and error bounds could not be computed.  RCOND = 0
  231.              is returned.  = N+1: U is nonsingular, but RCOND is less than
  232.              machine precision, meaning that the matrix is singular to working
  233.              precision.  Nevertheless, the solution and error bounds are
  234.              computed because there are a number of situations where the
  235.              computed solution can be more accurate than the value of RCOND
  236.              would suggest.
  237.  
  238. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  239.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  240.  
  241.      This man page is available only online.
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.